Where to Get Help

So you are writing a program and you’re stuck; maybe you cant seem to fix a bug or maybe you just don't know what the next step should be. This lecture is all about trying to give you a few resources to fix your issue, whatever it may be.

Before we begin though, I'd like to point out that you should, in my opinion, really spend a good chunk of time trying to fix the issue yourself before you go to somebody else pleading for the answer. There are a few reasons for this, the first is that not many people like to help people when the question is very easy to awnser for yourself via a quick google search. And secondly, struggling with a problem and finally cracking it is a often frustrating but nonetheless a good way to learn.

The second thing I'd like to say is that this lecture will contain a bunch of website links and obviously over time website can change, links can cease to function etc. And so please be aware that the last time these links where checked was:

7th Dec, 2017

The Help Built-in

Within Python itself, there is a help prompt; you can call it with or without arguments. And When you run it, you can view documentation.

So lets for argument sake suppose you are struggling understanding how a string method works. Lets run help and read the documentation.

So the above bit of code returns a paragraph of text explaining how the count method works. These notes are not designed to teach beginners, rather, they are mainly here to help developers and so for that reason you might not always fully understand everything being said. But nonetheless the help function is a really useful tool, especially if you do not have internet access.

Generally speaking all of Pythons documentation follows a familiar format, if you are getting help with a function or object method the first line will be telling you about the arguments and what the function returns (which is designated by an arrow '-> int').

The next paragraph(s) will describe what the function does and may include more specific details regarding the functions behaviour. There may even be a few example calls as well.

So the above line of code is the documentation for the float 'as_integer_ratio' method. The first line tells us that this function takes a float as input and returns a tuple of two integers. And then within the main paragraph we get told Python will raise an OverflowError if we pass infinity as an argument.

The last couple of lines are what’s known as 'doctests', they show you an example call and tell you the expected output is for that call; for example, we can see from the doctest here that calling the integer_ratio method with input 10.0 is supposed to return (10, 1).

In addition to using help in this way, you also provide no arguments (i.e. help() ) and enter into a interactive utility. Once asked, simply enter the subject you wish to learn about and type quit once you're done. For example, I was interested in Python’s 'pass' keyword and so I did the following:

>>> help()
"[...] Enter the name of any module, keyword, or topic to get help [...]"
> help keywords
"[...] Enter a keyword to get more help [...]"
> help pass

The "pass" statement
********************
pass_stmt ::= "pass"

"pass" is a null operation --- when it is executed, nothing happens.
It is useful as a placeholder when a statement is required
syntactically, but no code needs to be executed, for example:

def f(arg): pass    # a function that does nothing (yet)
class C: pass       # a class with no methods (yet)

help> quit 

So yeah, help is a pretty useful tool, even though the documentation is predominately aimed at helping developers it is still nonetheless a useful resource that may contain the answer to your question(s).

Online Documentation

URL: https://docs.python.org/3/

Pretty much everything you will find in "help" you will find online (and more besides). Personally I much prefer to use the online docs over the help built-in because the website has a much better interface. Its a super useful and powerful tool, but as beginners you may sometimes find descriptions a bit dense and full of jargon you do not (yet!) understand.

For example, here is the entry for the keyword 'min', which you can see for yourself here:

min(iterable, [, key, default])
min(arg1, arg2, args[, key])

Return the smallest item in an iterable or the smallest of two or more arguments.

If one positional argument is provided, it should be an iterable. The smallest item in the iterable is returned. If two or more positional arguments are provided, the smallest of the positional arguments is returned.

There are two optional keyword-only arguments. The key argument specifies a one-argument ordering function like that used for list.sort(). The default argument specifies an object to return if the provided iterable is empty. If the iterable is empty and default is not provided, a ValueError is raised.

If multiple items are minimal, the function returns the first one encountered. This is consistent with other sort-stability preserving tools such as sorted(iterable, key=keyfunc)[0] and heapq.nsmallest(1, iterable, key=keyfunc).

This is a good description of min, but as beginners you might find understanding some of this might require more googling, for example, 'sort-stability', 'iterable' etc may be concepts you unfamiliar with.

Stack Overflow

URL: https://stackoverflow.com/

Stackoverflow is a website where people ask questions and other members of the community try their best to answer. Personally I have never asked a question on there, but I cannot stress the number of times I've found the information I needed on this website; it turns out that if you are struggling with a problem someone else has probably struggled with that too.

To get the most out of it, you need to be think a little bit about your search, the better you are at using google the more likely you are to find what you want. Let me give you a real example I struggled with:

What I wanted to do was build a nested list, x is supposed to look like:

[[2, 2, 2],
 [2, 2, 2],
 [2, 2, 2]]

And then I wanted to change the value at index [0][0] but notice that instead of a single value changing the first item in every list changes. I wanted:

[["ZZ", 2, 2],
 [  2,  2, 2],
 [  2,  2, 2]]

But I got:

[["ZZ", 2, 2],
 ["ZZ", 2, 2],
 ["ZZ", 2, 2]]

Weird right?

Homework Assignment

Your homework for this week is to search google for an answer to this problem. Why doesn't X behave like I want it too and what to I need to make it work?

I know for a fact the answer is on stackoverflow already (and probably hundreds of other websites too), so this is a test of your googling skills:

“What search query is likely to return the information you need?”

This exercise is a really useful I think. Through-out your programming career you are going to stumped by tough questions. In many cases, the fastest way to solve your issue is going to be google search. BUT to get the most out of a search engine is going to require you to carefully think about the problem and what query might contain the answer.

Debugging Tools

"Give a plumber a toothbrush and he'll look at you like you are a total weirdo, but give him a plunger and he can fix your toilet."

I was kinda going for a thought-proving "teach a man to fish" type quote there but probably missed the mark.

Anyway, aphorisms aside the intended point here is that if you want to fix things, you need the right tools. One tool I find myself using often is Python Tutor:

URL: http://pythontutor.com/

This website allows you to run Python code in your browser. Although it is limited in what you can run (scripts must be less than 100 lines and cannot take more that 999 steps) it is a really simple yet useful tool for debugging. The feature this website has is the ability to run the program line by line and on the right-hand side you can see all the values your variables currently have.

There are lots of other debugging tools out there but I like this one because I think it is beginner friendly and because it runs in the browser it requires no setup (unlike, for example, debugging Python in VSCode)

Run Tests

I'm going to talk about testing in more detail in the next few lectures, but I thought it was worth briefly mentioning here. If a piece of code is isn't working properly, you can try running a few tests to see if you can isolate the issue.

Ask people

If all else fails, joining some sort of community and asking for help is probably a good idea. Forums, chat rooms, whatever. Basically you just wanna find the place where all the helpful people hang out. :)

Anyway, that’s it for today, don’t forget your homework!